Skip to content

ProjectOverview.md

Latest commit

 

History

History
249 lines (194 loc) · 16.1 KB

ProjectOverview.md

File metadata and controls

249 lines (194 loc) · 16.1 KB
Raw

Eurobot 2027 Navigation2 — Project Overview

給 AI、開發者與維護者使用的快速上下文文件。內容以目前 repository 的原始碼、launch、CMake 與 YAML 為準；若本文件與程式碼不一致，以程式碼為準並更新本文件。

開發環境規則：所有 build、run、test、ROS 指令都必須在 Docker 容器內執行。 Host 端只負責編輯 source、執行 nav2.sh 與管理 Docker；不要在 host 直接執行 colcon 或 ros2。

1. 專案定位

本專案是 DIT Robotics Eurobot 2027 的 ROS 2 Navigation2 workspace，基於 ROS 2 Humble / Ubuntu 22.04。它把 Nav2 的 global planning、local control、costmap、Behavior Tree、lifecycle 與 RViz，整合 Eurobot 場地的避障、對手偵測、物件偵測、keepout 區域、模擬 odometry、路徑腳本及 docking。

重要特性：

  • 全向輪（holonomic / omnidirectional）機器人設定。
  • 自訂 controller：一般 custom controller 與 TEB controller，多組速度 profile。
  • 自訂 costmap layer：keepout_layer、object_layer、rival_layer、sima_layer。
  • 自訂 Navigate-to-pose / Navigate-through-poses BT，包含 controller 與 goal-checker selector。
  • 修改過的 NavFn 與 SmacPlanner2D，加入避障偏置、plateau fallback 及直線化路徑重採樣。
  • OpenNav Docking 整合 /dock_robot，並可從 docking 選擇 controller、goal checker 與 docking 行為。
  • Docker 封裝 build、development、runtime 與 VNC 環境。

2. 專案結構

.
├── README.md                         # 對外功能與 Docker quick start
├── ProjectOverview.md                # 本文件；AI 先讀這裡
├── nav2.sh                           # Docker workflow wrapper
├── docker/
│   ├── local/                        # local build/dev/run compose
│   ├── deploy/                       # deployment compose、Dockerfile、scripts
│   └── vnc/                          # GUI/VNC compose 與 image
└── src/
    ├── Navigation2/                  # vendored / modified Nav2 packages
    ├── navigation2_run/              # launch、params、map、sim/helper nodes
    ├── custom_controller/             # custom_controller + teb_controller plugins
    ├── custom_layer/                  # 四個 costmap plugin 及其 simulator
    ├── custom_bts/                    # custom navigation BT XML / selector
    ├── opennav_docking/               # docking server、BT、core、interfaces
    ├── camera_offset_publisher/       # camera pose / velocity / dock-side helper
    └── btcpp_ros2_interfaces/         # custom BT startup service

ROS package 分類

區域 Packages / 內容
Modified Nav2 nav2_behavior_tree, nav2_behaviors, nav2_bt_navigator, nav2_common, nav2_controller, nav2_core, nav2_costmap_2d, nav2_lifecycle_manager, nav2_map_server, nav2_msgs, nav2_navfn_planner, nav2_planner, nav2_rviz_plugins, nav2_smac_planner, nav2_smoother, nav2_util, nav2_velocity_smoother, nav2_waypoint_follower
Bringup / helpers navigation2_run, camera_offset_publisher, btcpp_ros2_interfaces
Custom controller custom_controller
Custom costmap keepout_layer, object_layer, rival_layer, sima_layer
Custom BT custom_nav_to_pose, custom_nav_thru_poses
Docking opennav_docking, opennav_docking_bt, opennav_docking_core, opennav_docking_msgs

3. 啟動流程

sim_launch.py / real_launch.py
        │ 選 map、params、RViz、odometry simulation
        ▼
bringup_launch.py
        ├── localization_launch.py
        │     ├── nav2_map_server / map_server
        │     ├── lifecycle_manager_localization
        │     └── odometry_sim（僅 use_odometry_sim=true）
        └── navigation_launch.py
              ├── controller_server
              ├── smoother_server
              ├── planner_server
              ├── behavior_server
              ├── bt_navigator
              ├── waypoint_follower
              ├── velocity_smoother
              ├── lifecycle_manager_navigation
              └── docking_server

預設使用 composition：bringup_launch.py 建立 nav2_container（component_container_isolated），再載入上述 composable nodes。將 use_composition:=False 時則啟動一般 processes。system_check 會等待 /robot/startup/are_you_ready，確認 startup service、navigate_to_pose action 與 dock_robot action 可用後，呼叫 /robot/startup/ready_signal。

Launch files

Launch 用途與預設行為
src/navigation2_run/launch/sim_launch.py Simulation entry point；use_rviz=true、use_odometry_sim=true、pose remap 預設 /final_pose。
src/navigation2_run/launch/real_launch.py Real-robot entry point；use_rviz=false、use_odometry_sim=false、pose remap 預設 /local_pose。
bringup_launch.py 組合 localization 與 navigation，負責 namespace、composition、params。
localization_launch.py map server、localization lifecycle manager、可選 odometry_sim。目前此專案未在 launch 內啟動 AMCL。
navigation_launch.py 啟動 navigation / docking servers。
rviz_launch.py 啟動 rviz/rviz_sim.rviz。
script_launch.py 啟動 navigation2_run/script_sim，讀取 script YAML。

sim_launch.py 與 real_launch.py 會依環境變數 ROS_DOMAIN_ID 自動選參數：11 → nav2_params_11.yaml、13 → nav2_params_13.yaml、14 → nav2_params_14.yaml，其他值使用 nav2_params_default.yaml。Docker wrapper 若未設定，會將 ROS_DOMAIN_ID 預設為 100，因此通常會落到 default。

4. 主要介面與資料流

Actions / services / control topics

介面 型別 用途
/navigate_to_pose nav2_msgs/action/NavigateToPose 單一目標導航
/navigate_through_poses Nav2 action 多 waypoint 導航
/dock_robot opennav_docking_msgs/action/DockRobot docking action
/robot/startup/are_you_ready std_msgs/msg/Bool 觸發 system_check
/robot/startup/ready_signal btcpp_ros2_interfaces/srv/StartUpSrv 回報 navigation group ready（group=3、state=1）
/controller_type、/controller_type_thru std_msgs/msg/String 選 controller；使用 reliable + transient-local QoS
/goal_checker_type std_msgs/msg/String 選 goal checker
/controller_function std_msgs/msg/String docking controller function
/dock_controller_type std_msgs/msg/String docking controller type
/stopRobot std_msgs/msg/Bool docking server 的 stop / unlock
/keepout_zone std_msgs/msg/String 動態切換 keepout zone
cmd_vel / cmd_vel_nav geometry_msgs/msg/Twist 最終或導航速度；navigation launch 內有 remap
/local_pose、/final_pose nav_msgs/msg/Odometry 實車 / 模擬 pose，依 launch remap 使用

主要導航鏈：localization / odometry → costmap → planner → global path → BT navigator → controller → velocity smoother → cmd_vel。Docking server 在 docking action 活躍時也會產生速度命令。

5. 客製元件

5.1 Controllers

custom_controller 以 Nav2 controller plugin 形式輸出全向速度；teb_controller 實作 TEB 風格短視窗軌跡最佳化。Plugin XML 位於 src/custom_controller/resource/custom.xml 與 teb.xml。參數中的常見 profile 是 Fast、Slow、LinearBoost、AngularBoost，另外依 domain YAML 可能使用 DidilongController。

修改 controller 或 selector 時，必須同步檢查：

  1. src/navigation2_run/params/nav2_params_*.yaml 的 controller_plugins。
  2. src/custom_controller/resource/*.xml 的 plugin class name。
  3. ControllerSelector.cpp、nav_type_selector.cpp 使用的字串（大小寫需一致）。
  4. 對應 goal checker 名稱（例如 Precise、Loose、DidilongGoalChecker）。

5.2 Costmap layers

Layer 主要輸入 / 行為
keepout_layer 從 YAML 的 keepout_zone_array 建立矩形區域；以 /keepout_zone (String) 動態更新；可用 circle/square expand mode。區域圖示在 src/custom_layer/keepout_layer/*index.png。
object_layer 讀取 column、platform、obstacle、overturn 的 PoseArray，以及 robot odometry，將偵測到的場物件寫入 costmap。測試 publisher 是 ObjectSim。
rival_layer 讀取 /rhino_pose (nav_msgs/msg/Odometry) 與 rival distance，依對手狀態、速度、不確定性與安全半徑膨脹障礙；可由 external_rival_data_path 載入 nav_rival_parameters。
sima_layer 讀取 /sima_<id>/odom 與 /sima_<id>/distance，依多個 SIMA 物件及 localization / velocity 統計調整膨脹與避障。參數包含 sima_ids、global_frame、safe_distance 等。

每個 layer 都透過各自的 *layer.xml 以 pluginlib export；實際是否啟用及參數位置要以 nav2_params_*.yaml 中 global/local costmap 的 plugin list 為準。

5.3 Behavior Trees

  • custom_nav_to_pose/behavior_trees/navigate_to_pose_w_selector.xml
  • custom_nav_thru_poses/behavior_trees/navigate_through_poses_w_selector.xml

這兩棵 BT 由參數中的 default_nav_to_pose_bt_xml / default_nav_through_poses_bt_xml 指定，負責 selector、recovery、replanning 等流程。不要只修改 XML；若新增 BT node，還要更新 plugin library、CMake 及 navigator 的 plugin_lib_names。

5.4 Planner modifications

nav2_navfn_planner：

  • 將 costmap cost 映射到 NavFn cost，加入 heuristic_scale、priority_increment_scale。
  • 以 obstacle_bias_scale、obstacle_bias_offset 避免過度貼近高 cost 區域。
  • path extraction 加入 gradient / plateau stagnation 偵測與 fallback；相關參數包括 plateau_stagnation_steps、min_gradient_norm、potential_epsilon。

nav2_smac_planner 的 2D planner：

  • A* 後對可直視的節點做 line-of-sight simplification。
  • 對簡化後 segment 重採樣，使路徑較直且 pose orientation 一致。
  • 參數：straight_line_max_skip_points、straight_line_resample_points、straight_line_resample_spacing。

6. 設定檔地圖

路徑 說明
src/navigation2_run/params/nav2_params_default.yaml 預設完整 Nav2 / custom plugin 設定。
src/navigation2_run/params/nav2_params_11.yaml、_13.yaml、_14.yaml 依 robot / domain 的實機 override；修改前先比較 controller、pose topic、BT 與 layer 參數。
src/navigation2_run/params/dynamic_params/*.yaml runtime tuning profile：rival、didilong、fast、slow、linearBoost、angularBoost；格式說明在 params_formats.md。
src/navigation2_run/params/script.yaml ScriptSim 的 points；格式為 `[path
src/navigation2_run/maps/basic_map.yaml + mat2027.png 目前 bringup 的預設地圖。
src/navigation2_run/rviz/rviz_sim.rviz RViz 預設視圖。

參數檔中常見 frame / pose 假設是 map、base_footprint 與 /local_pose；simulation 另外透過 /final_pose。若導航看似啟動但沒有有效定位，優先檢查 remap、TF、use_sim_time 和 domain。

7. Docker 與常用命令

Docker image 以 ros:humble-ros-base-jammy 為基礎。推薦從 repository root 執行：

./nav2.sh tools       # 顯示完整命令
./nav2.sh rebuild     # 重建 images
./nav2.sh build       # 在 navigation-build 內 colcon build
./nav2.sh dev         # 進入 development container
./nav2.sh run         # detached 啟動 runtime（real_launch.py）
./nav2.sh vnc         # 啟動 VNC / RViz 環境
./nav2.sh logs run    # 查看服務 logs
./nav2.sh exec dev "ros2 topic list"
./nav2.sh ps
./nav2.sh stop [service]
./nav2.sh clean

容器內的 ROS 流程

若需要手動操作 ROS，先進入 development container，再於容器內執行：

./nav2.sh dev                 # Host 端執行；進入 navigation-develop
# 以下指令全部在 Docker container 內執行
source /opt/ros/humble/setup.bash
colcon build --symlink-install
source install/local_setup.bash
ros2 launch navigation2_run sim_launch.py
# 或：ros2 launch navigation2_run real_launch.py

./nav2.sh build 會在 navigation-build container 內編譯；./nav2.sh run 會在 navigation-run container 內啟動實機 launch；./nav2.sh vnc 用於需要 GUI 的 RViz。若使用 local compose，對應的 service 名稱是 navigation-develop-local、navigation-build-local、navigation-run-local。

注意：nav2.sh run 的 runtime 預設執行 real_launch.py；simulation 請在 container 內明確執行 ros2 launch navigation2_run sim_launch.py，或檢查 compose override。

8. 除錯順序

  1. 先進入 Docker，確認 image、ROS distro、ROS_DOMAIN_ID、DDS middleware（Docker 安裝 CycloneDDS）。
  2. ros2 node list 確認 map_server、planner_server、controller_server、bt_navigator、docking_server 已啟動並完成 lifecycle。
  3. ros2 topic list / ros2 topic echo 檢查 /local_pose 或 /final_pose、/map、cmd_vel、selector topics。
  4. 檢查 TF：map → odom/local_pose → base_footprint，以及 launch 中的 pose remap。
  5. 導航無路徑時，檢查 global/local costmap 是否被 custom layer 全部標障礙；再檢查 planner 參數與 map resolution。
  6. docking 問題檢查 /dock_robot action、dock pose、/dock_side、/controller_function、battery/joint-state input。
  7. 啟動 handshake 問題檢查 /robot/startup/are_you_ready、/robot/startup/ready_signal 及兩個 action server；system_check 只在收到 Bool(true) 後檢查依賴。

9. 修改守則（for AI）

  • 先讀本文件，再只深入與任務相關的 package；不要每次掃描整個 src/Navigation2。
  • 任何 plugin 修改都要同時檢查 header、implementation、plugin XML、CMake、package.xml 與對應 YAML。
  • 優先修改 navigation2_run 的整合層；除非需求明確，不要把 upstream Nav2 package 大幅重構。
  • 新增 ROS interface 時同步更新 .srv / .action、CMake generators、package dependencies 與所有 client/server。
  • 修改 launch 時同時確認 composition 與 non-composition 兩條路徑，以及 simulation / real 的預設差異。
  • 只要改動 controller、planner、costmap 或 BT，至少在 Docker 內執行相關 package 的 colcon build；可行時再在 Docker 內執行 colcon test。
  • script_sim.cpp 目前包含固定的舊 workspace 絕對路徑邏輯；若要讓腳本可攜，應優先改成使用 launch 傳入的 params_file 或 package share directory。
  • 不要把 __pycache__、build artifacts、runtime CSV 與 Docker generated files 當成 source of truth。

10. 已知注意事項

  • Repository root 的 README.md 偏向功能與操作說明；本文件偏向架構與 Codex 上下文。
  • src/Navigation2 內有 upstream Nav2 的大量 package；只有部分 planner / navigator / costmap 等檔案是本專案真正需要優先關注的客製點。
  • nav2_params.yaml 是部分 launch 的原始 default path，但 repository 實際提供的是 nav2_params_default.yaml 及 domain-specific files；實際 entry point sim_launch.py / real_launch.py 會傳入正確檔案。
  • script.yaml 開頭目前示範的是 path、dock，並保留大量註解中的 wait 測試點；修改腳本前確認 ScriptSim 的五欄解析與 action server 是否在線。
  • 這份 overview 是快速索引，不取代對正在修改之函式、plugin contract、YAML hierarchy 與 ROS message definition 的逐檔確認。

11. 快速索引

  • 對外功能：README.md
  • 啟動整合：src/navigation2_run/launch/
  • 導航參數：src/navigation2_run/params/
  • 地圖與 RViz：src/navigation2_run/maps/、src/navigation2_run/rviz/
  • controller：src/custom_controller/
  • costmap：src/custom_layer/
  • BT：src/custom_bts/、src/Navigation2/nav2_bt_navigator/behavior_trees/
  • planner：src/Navigation2/nav2_navfn_planner/、src/Navigation2/nav2_smac_planner/
  • docking：src/opennav_docking/
  • Docker：docker/、nav2.sh