TF Tree: debug cây hệ toạ độ khi Nav2 báo lỗi transform

Bài Transform giải thích TF tree về mặt lý thuyết — chuỗi các phép biến đổi nối map → odom → base_link → lidar_link. Bài này là phần thực hành: khi một node báo lỗi "could not transform", đây là quy trình xác định chính xác đoạn nào trong chuỗi đang thiếu hoặc sai.

Khái niệm chính

Hai công cụ debug TF chính, mỗi công cụ trả lời một câu hỏi khác nhau:

view_frames — chụp lại toàn bộ cây TF tại một thời điểm, trả lời "cấu trúc tổng thể có đúng không"
tf2_echo — theo dõi một cặp frame cụ thể theo thời gian thực, trả lời "giá trị cụ thể giữa 2 frame này ngay bây giờ là gì"

Nguyên lý hoạt động

ros2 run tf2_tools view_frames

Lệnh này lắng nghe TF trong vài giây, sau đó xuất ra file frames.pdf — sơ đồ cây đầy đủ mọi frame đang tồn tại và quan hệ cha-con giữa chúng, kèm theo tần số publish và độ trễ (delay) của từng transform. Đây là bước đầu tiên nên làm khi nghi ngờ có vấn đề về TF — nhìn tổng thể trước khi đi vào chi tiết từng cặp frame.

Đọc sơ đồ, tìm frame bị "mồ côi" hoặc tần số bất thường:

Frame "mồ côi" (không nối vào cây chính) → thiếu static_transform_publisher
                                             hoặc node publish frame đó chưa chạy

Tần số publish quá thấp (ví dụ map→odom chỉ 1Hz thay vì 10Hz kỳ vọng)
    → node nguồn (thường là ekf_global hoặc amcl) đang chạy chậm/quá tải

Độ trễ (delay) lớn giữa lúc data được tạo và lúc publish
    → có thể gây lỗi "extrapolation" khi node khác cần transform tại
      thời điểm chưa có dữ liệu

ros2 run tf2_ros tf2_echo map base_link

Khác view_frames (chụp một lần), tf2_echo in liên tục translation + rotation giữa 2 frame theo thời gian thực — hữu ích để xác nhận một transform cụ thể có đang cập nhật đúng hay không, hoặc để lấy nhanh vị trí hiện tại của robot trong hệ map mà không cần viết code.

Tóm lại: Luôn bắt đầu bằng view_frames để khoanh vùng, rồi dùng tf2_echo để đào sâu vào đúng cặp frame nghi vấn.

Kiến thức kỹ thuật

Công thức

TF buffer chỉ giữ dữ liệu trong một khoảng thời gian giới hạn (mặc định thường 10 giây) — lỗi "Lookup would require extrapolation" xảy ra khi truy vấn nằm ngoài cửa sổ này:

Truy vấn hợp lệ khi: thời_điểm_hiện_tại - buffer_duration ≤ thời_điểm_truy_vấn ≤ thời_điểm_hiện_tại

Nếu node subscriber xử lý dữ liệu chậm hơn buffer_duration trước khi
cần transform tại đúng timestamp của dữ liệu đó -> lỗi "extrapolation into the past"

Nếu node yêu cầu transform tại thời điểm CHƯA XẢY RA (timestamp tương lai,
thường do đồng hồ lệch giữa các máy) -> lỗi "extrapolation into the future"

Thông số

Công cụ	Dùng để
`ros2 run tf2_tools view_frames`	Chụp toàn bộ cây TF, xuất PDF
`ros2 run tf2_ros tf2_echo A B`	Theo dõi 1 cặp frame theo thời gian thực
RViz2 Display `TF`	Xem trực quan 3D (bài RViz2)
`ros2 topic hz /tf`	Kiểm tra tần số publish tổng thể

Ứng dụng thực tế

Lỗi "Lookup would require extrapolation into the past/future" là lỗi TF phổ biến nhất khi chạy Nav2 trên kiến trúc nhiều máy (như PC + Jetson trong dự án Atlas A2, hoặc MCU + SBC nói chung đã học ở bài Kiến trúc AMR) — nguyên nhân thường gặp gồm đồng hồ hệ thống giữa các máy không đồng bộ (đã nhắc ở bài DDS Configuration) khiến timestamp lệch nhau, hoặc một node publish TF trễ hơn nhiều so với các node khác. Kiểm tra đồng bộ đồng hồ là bước đầu tiên nên làm với lỗi này, trước khi nghi ngờ logic code — dùng chrony/ntpdate để đồng bộ giờ giữa các máy tham gia cùng hệ thống ROS2.

Ví dụ thực tế

# Quy trình debug đầy đủ khi Nav2 báo "could not transform"

# Bước 1: chụp toàn cảnh
ros2 run tf2_tools view_frames
# -> mở frames.pdf, tìm frame mồ côi hoặc tần số bất thường

# Bước 2: đào sâu vào cặp frame nghi vấn (VD: map -> odom)
ros2 run tf2_ros tf2_echo map odom
# -> nếu không có output, node nguồn (ekf_global) chưa publish đúng

# Bước 3: kiểm tra đồng bộ đồng hồ giữa các máy (nếu multi-machine)
timedatectl status   # trên mỗi máy, so sánh giờ hệ thống

# Bước 4: nếu lệch, đồng bộ lại
sudo apt install chrony
sudo systemctl restart chrony

Kịch bản thực tế: Nav2 chạy trên Jetson báo lỗi extrapolation liên tục,
trong khi node driver động cơ chạy trên máy tính riêng qua mạng LAN

Nguyên nhân xác định qua quy trình trên: đồng hồ hệ thống giữa Jetson
và máy driver lệch nhau ~2 giây do không cùng đồng bộ NTP
-> timestamp trong TF message publish từ máy driver bị coi là "trong quá khứ"
   khi Jetson nhận và so với buffer TF của chính nó
-> đồng bộ lại đồng hồ bằng chrony giải quyết hoàn toàn lỗi

Lỗi thường gặp

Nghi ngờ logic code trước khi kiểm tra đồng bộ đồng hồ trong hệ nhiều máy — như ví dụ trên, nguyên nhân phổ biến nhất của lỗi extrapolation trong kiến trúc multi-machine là lệch đồng hồ, không phải lỗi thuật toán.
Chỉ dùng tf2_echo mà bỏ qua view_frames để nhìn tổng thể trước — dễ bỏ sót vấn đề ở một đoạn TF khác không phải cặp frame đang debug trực tiếp.
Không kiểm tra tần số publish TF trước khi kết luận "TF bị lỗi" — tần số quá thấp so với kỳ vọng (node nguồn quá tải) khác hẳn với TF hoàn toàn không publish, cần phân biệt rõ hai tình huống này qua ros2 topic hz /tf.
Bỏ qua kiểm tra frame "mồ côi" trong sơ đồ view_frames — một static_transform_publisher chưa chạy hoặc node publish frame đó gặp lỗi tạo ra frame không kết nối vào cây chính, dễ bị bỏ sót nếu không nhìn tổng thể trước.

Kết luận

Debug TF tree hiệu quả luôn theo đúng trình tự: view_frames để khoanh vùng cấu trúc tổng thể, tf2_echo để đào sâu vào cặp frame nghi vấn, và kiểm tra đồng bộ đồng hồ nếu chạy kiến trúc nhiều máy. Đây là bài cuối của chuyên mục Localization — từ AMCL, EKF, RF2O, hợp nhất odometry, tới debug TF tree, chuỗi 5 bài đã đi từ lý thuyết định vị tới thực hành triển khai hoàn chỉnh trong Nav2. Chuyên mục Nav2 tiếp theo đi vào các thành phần còn lại của framework — Planner, Controller, Costmap, Behavior Tree.