move_base2/docs/ARCHITECTURE.md

Kiến trúc

Ba lớp

┌──────────────────────────────────────────────────────────────────────┐
│  Biên (adapter)                                                      │
│                                                                      │
│  NavigationServer  ──implements──▶  move_base_core::BaseNavigation   │
│    · quy 6 entry point di chuyển về 1 NavigationRequest              │
│    · nhận dữ liệu sensor từ host                                     │
│    · kết xuất trạng thái ra kiểu mà host mong đợi                    │
└──────────────────────────────────┬───────────────────────────────────┘
                                   │
┌──────────────────────────────────▼───────────────────────────────────┐
│  Điều phối                                                           │
│                                                                      │
│  ControlLoop — một control cycle: gom dữ liệu, chạy state machine,   │
│                thi hành output, phát lệnh vận tốc                    │
└──────────────────────────────────┬───────────────────────────────────┘
                                   │
┌──────────────────────────────────▼───────────────────────────────────┐
│  Lõi quyết định (logic thuần, không I/O)                             │
│                                                                      │
│  StateMachine      — bảng chuyển state                               │
│  VelocityArbiter   — ai được phát lệnh, và lệnh đó có an toàn không  │
│  NavigationRequest — kiểu dữ liệu duy nhất đi vào lõi                │
└──────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼  (qua port, không qua kiểu cụ thể)
     ClockPort   PosePort   PlannerPort   ControllerPort
                 RecoveryPort   MissionPort   ActionPort

Lõi không đụng costmap, không đụng TF, không log, không cấp phát trong vòng lặp. Vì vậy nó kiểm được bằng bảng thay vì phải dựng runtime hay chạy robot.

Chiều phụ thuộc

move_base2 ──▶ mission framework
           ──▶ recovery framework

Một chiều, không có đường ngược. Hai framework kia không biết move_base2 tồn tại và không biết lẫn nhau. Hệ quả có thật, không phải hình thức:

• Ba gói test được độc lập.
• Không có vòng phụ thuộc trong build.
• move_base2 không bị khoá cứng vào một hiện thực mission hay recovery cụ thể — đổi framework chỉ cần viết lại lớp nối, không phải sửa lõi.

Ở Phase 1, chiều này còn được giữ ở mức mạnh hơn: không file nào trong move_base2 include ba framework kia. Lớp nối được thêm ở bước sau và chúng mới là chỗ duy nhất được phép include: RecoveryRunner cho recovery_core; ActionRunner cho action_core; bridges/mission_adapter_bridge (dịch contract) và bridges/mission_layer (lắp ráp registry + hàng đợi + hai thread) cho mission_adapters.

Kiểm bằng:

grep -rn "mission_adapters\|recovery_core\|action_core" src/AMR_T800/Test/move_base2/include \
                                                        src/AMR_T800/Test/move_base2/src

Vì sao là port chứ không phải gọi thẳng

Bảy port đều nhỏ và đều tồn tại vì một lý do vận hành cụ thể:

Port	Lý do tồn tại
ClockPort	Không có nguồn thời gian tiêm được thì không cách nào kiểm hành vi khi control loop chạy chậm hơn chu kỳ cấu hình — đúng lớp lỗi mà dead-reckoning theo chu kỳ danh nghĩa mắc phải
PosePort	Contract "trả false = dừng an toàn" phải kiểm được mà không cần dựng TF thật
PlannerPort	Gộp hai overload makePlan của interface gốc thành một; "có Order hay không" chỉ là một nhánh nhỏ bên trong
ControllerPort	Giữ nguyên bộ hàm và thứ tự gọi của interface được bọc (hỏi đã tới đích trước, chỉ khi chưa mới tính lệnh)
RecoveryPort	Chuẩn hoá kết quả tick về ngôn ngữ của move_base2, để lõi không phải include recovery framework
MissionPort	Luồng một chiều có callback, thay cho việc phía mission phải poll trạng thái navigation
ActionPort	(D8) Runtime điều phối trọn một mission — nav xong chạy nốt action rồi mới báo kết quả. Tick-based cùng nhịp control loop như recovery, và tick của nó không có vận tốc: action cần chuyển động phải là motion profile, không phải action

Quyết định thiết kế đáng ghi lại

Sáu entry point gộp về một contract lõi. moveTo ×2, dockTo ×2, moveStraightTo, rotateTo của contract host chỉ khác nhau ở kiểu chuyển động. moveTo(PoseStamped) là direct position goal nên trước tiên đi MissionLayer::submitGoal() → GoalSourceAdapter → MissionManager; nhờ đó nó nhận mission ID và lifecycle/cancel giống VDA5050. Nếu mission layer bị tắt hoặc không nạp source này mới fallback tương thích về NavigationRequest trực tiếp. Các API mang profile/marker riêng (dockTo, moveStraightTo, rotateTo) dựng request trực tiếp, vì schema geometry.pose_stamped chưa biểu diễn được marker/profile của chúng.

Một đường vào duy nhất. ControlLoop::submit() là chỗ duy nhất một goal lọt được vào lõi, và IDLE → PLANNING là transition duy nhất bắt đầu một chặng. Nhờ đó việc chống hai nguồn goal tranh nhau là tính chất cấu trúc, không phải thứ phải nhớ khoá bằng tay.

Từ chối tại cửa. Goal có quaternion hỏng, toạ độ không hữu hạn, hoặc profile không nạp được planner đều bị từ chối ngay trong submit() kèm lý do — không để state machine bắt đầu một chặng rồi mới phát hiện không có planner nào chạy được.

Phản hồi trễ một cycle. State machine chạy với phản hồi thu được từ cycle trước, rồi mới gọi cổng. Điều này là tường minh và có chủ đích: nó cắt vòng "gọi để biết nên gọi gì", nhờ vậy output của state machine là một danh sách hành động thuần tuý.

Lệnh 0 là tức thì. Nguồn kNone phát đúng 0, không giảm tốc dần. Lệnh vận tốc bị chốt lại ở tầng dưới, nên nếu control loop dừng giữa lúc đang giảm tốc thì lệnh khác 0 cuối cùng vẫn còn hiệu lực. Việc giảm tốc theo động học thuộc về bộ điều khiển bánh xe, nơi biết tải và ma sát thật.

Trạng thái hiện tại và phần còn thiếu

Đã có và chạy được:

• Toàn bộ lõi quyết định, có test phủ đủ bảng chuyển state.
• ControlLoop chạy end-to-end với thành phần giả.
• NavigationServer hiện thực đủ contract host.
• SensorGateway: dữ liệu cảm biến đi từ contract host tới đúng layer của hai costmap, có phát lại static map nhận trước khi costmap tồn tại. Đây là file duy nhất trong gói include robot_costmap_2d.
• getTwist() trả lệnh vận tốc từ VelocityArbiter, đóng dấu theo đồng hồ của control loop.
• Plugin libmove_base2.so export alias MoveBase2.

Bước nối dây runtime đã xong (Phase 4):

• PlannerRunner / ControllerRunner / RecoveryRunner / ActionRunner nạp plugin thật qua boost::dll; CostmapPosePort lấy pose từ costmap — hai instance, khác frame (map cho planner, odom cho controller/recovery).
• NavigationRuntime dựng hai Costmap2DROBOT thật rồi trả về ControlLoopDeps. NavigationServer::attachCostmaps() vẫn nhận LayeredCostmap* từ ngoài để đường cảm biến kiểm được mà không cần TF và cây config thật.
• Thread planner riêng + hoán vị ba buffer, PlannerPort bất đồng bộ.
• setTwistLinear / setTwistAngular — trần vận tốc, không phải lệnh jog.
• Lớp nối tới mission framework: MissionAdapterBridge (dịch contract) + MissionLayer (dựng registry, hàng đợi, hai thread). Order VDA5050 vào bằng moveTo(Order, …) được cắt thành từng chặng. Direct position goal vào bằng moveTo(PoseStamped) đi GoalSourceAdapter, vì vậy cũng có mission ID thay vì 0; tắt bằng mission_layer_enabled: false thì cả hai loại fallback xuống đường direct tương thích.

Chưa có:

• Kết xuất lưới costmap cho rviz đã có, nhưng đường OccupancyGridUpdate incremental đã bị bỏ — luôn gửi lưới đầy đủ ở 1 Hz.
• Action chạy dọc đường đi (edge action): mọi action hiện chạy sau khi tới goal của chặng.